Astring is a lightweight JavaScript library used for generating JavaScript code from an Abstract Syntax Tree (AST). It is designed to be fast and efficient, making it suitable for use in compilers, transpilers, and other tools that need to generate JavaScript code programmatically.
Basic Code Generation
This feature allows you to generate JavaScript code from a simple AST. In this example, astring generates a string literal from the provided AST.
const astring = require('astring');
const ast = { type: 'Literal', value: 'Hello, world!' };
const code = astring.generate(ast);
console.log(code); // Output: 'Hello, world!'
Complex Code Generation
This feature demonstrates generating more complex JavaScript code from an AST. In this example, astring generates a variable declaration with an initializer.
const astring = require('astring');
const ast = {
type: 'Program',
body: [
{
type: 'VariableDeclaration',
declarations: [
{
type: 'VariableDeclarator',
id: { type: 'Identifier', name: 'x' },
init: { type: 'Literal', value: 42 }
}
],
kind: 'const'
}
]
};
const code = astring.generate(ast);
console.log(code); // Output: 'const x = 42;'
Custom Code Generation
Astring allows for custom code generation by extending the base generator. In this example, the custom generator wraps the literal value in comment syntax.
const astring = require('astring');
const customGenerator = Object.assign({}, astring.baseGenerator, {
Literal(node, state) {
state.write(`/*${node.value}*/`);
}
});
const ast = { type: 'Literal', value: 'Hello, world!' };
const code = astring.generate(ast, { generator: customGenerator });
console.log(code); // Output: '/*Hello, world!*/'
Escodegen is another JavaScript library for generating JavaScript code from an AST. It is more feature-rich and supports a wider range of ECMAScript specifications compared to astring. However, it is also larger and may be slower in performance.
Babel-generator is part of the Babel toolchain and is used to generate JavaScript code from an AST. It is highly configurable and integrates well with other Babel tools. It is more heavyweight compared to astring and is typically used in larger projects that require extensive code transformations.
Recast is a library that not only generates JavaScript code from an AST but also preserves the original formatting and comments. It is useful for code refactoring and transformations where maintaining the original code style is important. Recast is more complex and larger in size compared to astring.
🌳 Tiny and fast JavaScript code generator from an ESTree-compliant AST.
:warning: Astring relies on
String.prototype.repeat(amount)andString.prototype.endsWith(string). If the environment running Astring does not define these methods, usestring.prototype.repeat,string.prototype.endsWithorbabel-polyfill.
Install with the Node Package Manager:
npm install astring
Or install with JSR:
deno add @davidbonnet/astring
Alternatively, checkout this repository and install the development dependencies to build the module file:
git clone https://github.com/davidbonnet/astring.git
cd astring
npm install
Import it from Deno's third party module repository:
const { generate } = await import('https://deno.land/x/astring/src/astring.js')
With JavaScript 6 modules:
import { generate } from 'astring'
With CommonJS:
const { generate } = require('astring')
A browser-ready minified bundle containing Astring is available at dist/astring.min.js. The module exposes a global variable astring:
<script src="astring.min.js" type="text/javascript"></script>
<script type="text/javascript">
var generate = astring.generate
</script>
The astring module exposes the following properties:
generate(node: object, options: object): string | objectReturns a string representing the rendered code of the provided AST node. However, if an output stream is provided in the options, it writes to that stream and returns it.
The options are:
indent: string to use for indentation (defaults to "␣␣")lineEnd: string to use for line endings (defaults to "\n")startingIndentLevel: indent level to start from (defaults to 0)comments: generate comments if true (defaults to false)output: output stream to write the rendered code to (defaults to null)generator: custom code generator (defaults to GENERATOR)sourceMap: source map generator (defaults to null)expressionsPrecedence: custom map of node types and their precedence level (defaults to EXPRESSIONS_PRECEDENCE)GENERATOR: objectBase generator that can be used to extend Astring.
EXPRESSIONS_PRECEDENCE: objectMapping of node types and their precedence level to let the generator know when to use parentheses.
NEEDS_PARENTHESES: numberDefault precedence level that always triggers the use of parentheses.
baseGenerator: object:warning: Deprecated, use
GENERATORinstead.
Operations per second for generating each sample code from a pre-parsed AST:
| code sample (length) | escodegen | astring | uglify | babel | prettier |
|---|---|---|---|---|---|
| tiny code (11) | 1,257,527 | 7,185,642 | 129,467 | 156,184 | 333 |
| everything (8532) | 1,366 | 8,008 | 0 | 346 | 64 |
Operations per second for parsing and generating each sample code:
| code sample (length) | acorn + astring | meriyah + astring | buble | sucrase |
|---|---|---|---|---|
| tiny code (11) | 92,578 | 864,665 | 25,911 | 575,370 |
| everything (8532) | 706 | 1,425 | 132 | 1,403 |
The following examples are written in JavaScript 5 with Astring imported à la CommonJS.
This example uses Acorn, a blazingly fast JavaScript AST producer and therefore the perfect companion of Astring.
// Make sure acorn and astring modules are imported
// Set example code
var code = 'let answer = 4 + 7 * 5 + 3;\n'
// Parse it into an AST
var ast = acorn.parse(code, { ecmaVersion: 6 })
// Format it into a code string
var formattedCode = astring.generate(ast)
// Check it
console.log(code === formattedCode ? 'It works!' : 'Something went wrong…')
This example uses the source map generator from the Source Map module.
// Make sure acorn, sourceMap and astring modules are imported
var code = 'function add(a, b) { return a + b; }\n'
var ast = acorn.parse(code, {
ecmaVersion: 6,
sourceType: 'module',
// Locations are needed in order for the source map generator to work
locations: true,
})
// Create empty source map generator
var map = new sourceMap.SourceMapGenerator({
// Source file name must be set and will be used for mappings
file: 'script.js',
})
var formattedCode = generate(ast, {
// Enable source maps
sourceMap: map,
})
// Display generated source map
console.log(map.toString())
This example for Node shows how to use writable streams to get the rendered code.
// Make sure acorn and astring modules are imported
// Set example code
var code = 'let answer = 4 + 7 * 5 + 3;\n'
// Parse it into an AST
var ast = acorn.parse(code, { ecmaVersion: 6 })
// Format it and write the result to stdout
var stream = astring.generate(ast, {
output: process.stdout,
})
// The returned value is the output stream
console.log('Does stream equal process.stdout?', stream === process.stdout)
Astring supports comment generation, provided they are stored on the AST nodes. To do so, this example uses Astravel, a fast AST traveller and modifier.
// Make sure acorn, astravel and astring modules are imported
// Set example code
var code =
[
'// Compute the answer to everything',
'let answer = 4 + 7 * 5 + 3;',
'// Display it',
'console.log(answer);',
].join('\n') + '\n'
// Parse it into an AST and retrieve the list of comments
var comments = []
var ast = acorn.parse(code, {
ecmaVersion: 6,
locations: true,
onComment: comments,
})
// Attach comments to AST nodes
astravel.attachComments(ast, comments)
// Format it into a code string
var formattedCode = astring.generate(ast, {
comments: true,
})
// Check it
console.log(code === formattedCode ? 'It works!' : 'Something went wrong…')
Astring can easily be extended by updating or passing a custom code generator. A code generator consists of a mapping of node names and functions that take two arguments: node and state. The node points to the node from which to generate the code and the state exposes the write method that takes generated code strings.
This example shows how to support the await keyword which is part of the asynchronous functions proposal. The corresponding AwaitExpression node is based on this suggested definition.
// Make sure the astring module is imported and that `Object.assign` is defined
// Create a custom generator that inherits from Astring's base generator
var customGenerator = Object.assign({}, astring.GENERATOR, {
AwaitExpression: function (node, state) {
state.write('await ')
var argument = node.argument
if (argument != null) {
this[argument.type](argument, state)
}
},
})
// Obtain a custom AST somehow (note that this AST is not obtained from a valid code)
var ast = {
type: 'AwaitExpression',
argument: {
type: 'CallExpression',
callee: {
type: 'Identifier',
name: 'callable',
},
arguments: [],
},
}
// Format it
var code = astring.generate(ast, {
generator: customGenerator,
})
// Check it
console.log(
code === 'await callable();\n' ? 'It works!' : 'Something went wrong…',
)
The bin/astring utility can be used to convert a JSON-formatted ESTree compliant AST of a JavaScript code. It accepts the following arguments:
-i, --indent: string to use as indentation (defaults to "␣␣")-l, --line-end: string to use for line endings (defaults to "\n")-s, --starting-indent-level: indent level to start from (defaults to 0)-h, --help: print a usage message and exit-v, --version: print package version and exitThe utility reads the AST from a provided list of files or from stdin if none is supplied and prints the generated code.
As in the previous example, these examples use Acorn to get the JSON-formatted AST. This command pipes the AST output by Acorn from a script.js file to Astring and writes the formatted JavaScript code into a result.js file:
acorn --ecma6 script.js | astring > result.js
This command does the same, but reads the AST from an intermediary file:
acorn --ecma6 script.js > ast.json
astring ast.json > result.js
This command reads JavaScript 6 code from stdin and outputs a prettified version:
cat | acorn --ecma6 | astring
FAQs
JavaScript code generator from an ESTree-compliant AST.
The npm package astring receives a total of 1,941,743 weekly downloads. As such, astring popularity was classified as popular.
We found that astring demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In an open letter, JavaScript community leaders urge Oracle to give up the JavaScript trademark, arguing that it has been effectively abandoned through nonuse.
Security News
The initial version of the Socket Python SDK is now on PyPI, enabling developers to more easily interact with the Socket REST API in Python projects.
Security News
Floating dependency ranges in npm can introduce instability and security risks into your project by allowing unverified or incompatible versions to be installed automatically, leading to unpredictable behavior and potential conflicts.